Banner

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen.

Start loading a banner

After initializing the SDK, call create() once with a valid placement ID and a banner size. Multiple calls with the same placement ID are ignored.

#include "x3mads/XMediatorAds.hpp"

// Initialize the SDK once, then create a banner
x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>",
    x3mads::InitSettings(),
    [](const x3mads::InitResult& result) {
        // Create and start loading a banner for a placement ID and size
        x3mads::XMediatorAds::getInstance()->banner->create(
            "<placement-id>", x3mads::BannerSize::PHONE
        );
    }
);

info

After creating a banner, you can call any show method even if it hasn't loaded yet. The SDK will automatically display the banner as soon as it finishes loading.

Showing a banner relative to the screen

You can position the banner relative to the screen, using the safe area or not.

// Show the banner at the bottom-center of the screen
x3mads::Position position(x3mads::Horizontal::CENTER, x3mads::Vertical::BOTTOM);
x3mads::XMediatorAds::getInstance()->banner->showRelativeToScreen(
    "<placement-id>", 
    position, 
    true // useSafeArea
);

info

Some networks (e.g., AppLovin, ironSource, or Unity Ads) may crop the banner if the safe area is ignored.

Showing a banner relative to the scene

You can position the banner relative to the scene coordinates with an offset.

warning

Important: You must call configure() once before using scene-relative APIs so the SDK can translate scene coordinates correctly.

// Show the banner relative to the scene with an offset (x, y)
x3mads::Position position(x3mads::Horizontal::RIGHT, x3mads::Vertical::TOP);
x3mads::XMediatorAds::getInstance()->banner->showRelativeToScene(
    "<placement-id>",
    position,
    x3mads::Point(40, 40)
);

Offset behavior

Horizontal offsets:

• When aligned to RIGHT: positive X moves banner LEFT (inward)
• When aligned to LEFT: positive X moves banner RIGHT (inward)

Vertical offsets:

• When aligned to TOP: positive Y moves banner DOWN (inward)
• When aligned to BOTTOM: positive Y moves banner UP (inward)

Use negative values to move in the opposite direction if needed.

Hiding a banner

Use this function to hide the banner. It does not interfere with loading; if the banner is still loading, it continues.

x3mads::XMediatorAds::getInstance()->banner->hide("<placement-id>");

Built-in features

Banner autorefresh

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built in auto retry for failed loads attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attemp will increase using an exponential backoff. You should not add any retry logic on your end, as it may interefere with our retry behaviour.

Banner sizes

Constant	Size (WxH)	Description
PHONE	320x50	Size for banners used in phone devices
TABLET	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Relative to the scene

Use bannerSizeOnScene() to obtain the banner dimensions in scene points for a given logical size (PHONE, TABLET, or MREC). This is useful for layout calculations (e.g., spacing UI elements).

warning

Important: You must call configure() once before using scene-relative APIs so the SDK can translate scene coordinates correctly.

auto size = x3mads::XMediatorAds::getInstance()->banner->bannerSizeOnScene(x3mads::BannerSize::PHONE);

Banner Position

x3mads::Position lets you control horizontal alignment, vertical alignment, and rotation.

Horizontal (x3mads::Horizontal):

Value	Description
LEFT	Align to the left edge
CENTER	Center horizontally
RIGHT	Align to the right edge

Vertical (x3mads::Vertical):

Value	Description
TOP	Align to the top edge
CENTER	Center vertically
BOTTOM	Align to the bottom edge

Rotation (x3mads::Rotation):

Value	Description
LEFT	Rotate 90° counterclockwise
NONE	No rotation
RIGHT	Rotate 90° clockwise

Example:

// RIGHT-CENTER, rotated RIGHT (90° clockwise)
x3mads::Position position(
    x3mads::Horizontal::RIGHT,
    x3mads::Vertical::CENTER,
    x3mads::Rotation::RIGHT
);
x3mads::XMediatorAds::getInstance()->banner->showRelativeToScreen("<placement-id>", position);

Additional settings

Add listener

Every ad callback indicates the placement ID of the banner that triggered the event.

// Register banner callbacks via a listener
struct MyBannerListener : public x3mads::BannerAdsListener {
    void onLoaded(const std::string& placementId, const x3mads::LoadResult& result) override {
        CCLOG("Banner loaded! placementId: %s", placementId.c_str());
    }
    void onImpression(const std::string& placementId, const x3mads::ImpressionData& data) override {
        CCLOG("Banner impression! placementId: %s", placementId.c_str());
    }
    void onClicked(const std::string& placementId) override {
        CCLOG("Banner clicked! placementId: %s", placementId.c_str());
    }
};

auto listener = new MyBannerListener();
x3mads::XMediatorAds::getInstance()->banner->addListener(listener);

Remove listener

If you add a listener, you should remove it when your scene/object is destroyed to stop receiving events.

void BannerExample::cleanup()
{
    x3mads::XMediatorAds::getInstance()->banner->removeListener(listener);
    Scene::cleanup();
}

Configure a banner relative to the scene

Important: Before showing a banner relative to the scene, you must call configure() once in your initialization code.

x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>",
    x3mads::InitSettings(),
    [](const x3mads::InitResult& result) {
        // Step 1: Get the viewport (actual screen area)
        auto glViewPort = Director::getInstance()->getOpenGLView()->getViewPortRect();
        auto viewPort = x3mads::Rect(
            x3mads::Point(glViewPort.origin.x, glViewPort.origin.y),
            x3mads::Size(glViewPort.size.width, glViewPort.size.height)
        );
        
        // Step 2: Get the design resolution (your game's coordinate system)
        auto glDesignResolution = Director::getInstance()->getOpenGLView()->getDesignResolutionSize();
        auto designResolution = x3mads::Size(glDesignResolution.width, glDesignResolution.height);

        // Step 3: Configure the banner system with both values
        // This allows the SDK to correctly translate between screen and scene coordinates
        x3mads::XMediatorAds::getInstance()->banner->configure(viewPort, designResolution);
    }
);

(Optional) Updating ad space

Before showing an ad, you can set an ad space name for the banner instance. This is useful for tracking purposes because it enables you to get performance insights for different ad spaces in your application.

x3mads::XMediatorAds::getInstance()->banner->setAdSpace(std::string("banner-ad-space"), "<placement-id>");

(Optional) Manually refreshing a banner ad

Banner ads usually refresh their contents automatically, after a certain amount of time has passed. However, if you prefer to, you can manually refresh a banner's content by calling the load method:

x3mads::XMediatorAds::getInstance()->banner->load("<placement-id>");

(Optional) Check if banner is ready

Calling isReady(placementId) returns whether a banner is available to be shown.

if (x3mads::XMediatorAds::getInstance()->banner->isReady("<placement-id>")) {
    x3mads::Position position(x3mads::Horizontal::CENTER, x3mads::Vertical::BOTTOM);
    x3mads::XMediatorAds::getInstance()->banner->showRelativeToScreen("<placement-id>", position);
}

Code example

Below is a Cocos2d-x example showing how to create and show a banner.

BannerExample.cpp

void showBannerBottomCenterScene() {
    x3mads::XMediatorAds::getInstance()->banner->setAdSpace(std::string("banner-ad-space"), "<placement-id>");
    x3mads::Position position(x3mads::Horizontal::CENTER, x3mads::Vertical::BOTTOM);
    x3mads::XMediatorAds::getInstance()->banner->showRelativeToScene(
        "<placement-id>", 
        position, 
        x3mads::Point(0, 50));
}

x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>", 
    x3mads::InitSettings(),
    [this](const x3mads::InitResult&) {
        auto glView = cocos2d::Director::getInstance()->getOpenGLView();
        auto glViewPort = glView->getViewPortRect();
        auto viewPort = x3mads::Rect(x3mads::Point(glViewPort.origin.x, glViewPort.origin.y),
                                    x3mads::Size(glViewPort.size.width, glViewPort.size.height));
        auto glDesignResolution = glView->getDesignResolutionSize();
        auto designResolution = x3mads::Size(glDesignResolution.width, glDesignResolution.height);

        x3mads::XMediatorAds::getInstance()->banner->configure(viewPort, designResolution);

        x3mads::XMediatorAds::getInstance()->banner->addListener(this);
        x3mads::XMediatorAds::getInstance()->banner->create("<placement-id>", x3mads::BannerSize::PHONE);

        showBannerBottomCenterScene();
    });